<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>The valueChange Event</title>
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
    <link rel="stylesheet" href="../assets/css/main.css">
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
    <script src="../../build/yui/yui-min.js"></script>
</head>
<body>

<div id="doc">
    <h1>The valueChange Event</h1>

    
        <a href="#toc" class="jump">Jump to Table of Contents</a>
    

    <div class="yui3-g">
        <div id="main" class="yui3-u">
            <div class="content"><div class="intro">
    <p>The <code>event-valuechange</code> module adds a "valueChange" event that fires
    when the <code>value</code> property of a text input element or textarea changes as
    the result of a keystroke, mouse operation, or input method editor (IME)
    input event.</p>
</div>

<h2 id="whats-the-problem">What's the problem?</h2>

<p>The input related events provided by browsers don't cleanly address the
variety of ways users can modify an &lt;input&gt; or &lt;textarea&gt;'s
<code>value</code>.  For example, users might change an input value by</p>

<ol>
    <li>typing a simple character</li>
    <li>typing a multi-stroke character</li>
    <li>
        using an <a href="http://en.wikipedia.org/wiki/Input_method">Input
        Method Editor</a>
    </li>
    <li>pasting a new value with <code>ctrl+V</code> or <code>cmd+V</code></li>
    <li>
        pasting a new value using the paste option from a right-click context
        menu.
    </li>
</ol>

<p>The ideal change event would fire when the value becomes <em>something it
wasn't a moment ago</em>.</p>

<p>The <code>valueChange</code> event provides more reliable input notifications than
native events like <code>oninput</code> and <code>textInput</code>, particularly with changes that
result from multiple-keystroke IME input.</p>

<pre class="code prettyprint">commentTextarea.on(&#x27;valueChange&#x27;, updateLivePreview);</pre>


<h2 id="how-it-works">How it works</h2>

<p><code>valueChange</code> subscriptions monitor the input's value using a variety of
mechanisms including subscriptions to <code>blur</code> and various keyboard events, and a
poll to catch the stragglers.  It seems like a lot of work, but it's the only
way to be sure.</p>

<p>The polling is only active when the input is focused, so the performance of your app should not be impacted.</p>

<h2 id="caveats">Caveats</h2>

<ol>
    <li><code>valueChange</code> does not (yet) support delegation</li>
    <li>
        <code>valueChange</code> only supports subscription on text &lt;input&gt;s and
        &lt;textarea&gt;s, though no steps are taken to ensure the subscribed
        node is one of these.  If you subscribe to a different type of node,
        and stuff breaks, you were warned.
    </li>
    <li>
        <code>valueChange</code> does not capture <code>value</code> updates done in JavaScript
        <em>unless the input is currently focused</em>.
        <code>node.set(&#x27;value&#x27;, &#x27;will probably not trigger valueChange&#x27;);</code>
    </li>
</ol>
</div>
        </div>

        <div id="sidebar" class="yui3-u">
            
                <div id="toc" class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Table of Contents</h2>
                    </div>

                    <div class="bd">
                        <ul class="toc">
<li>
<a href="#whats-the-problem">What's the problem?</a>
</li>
<li>
<a href="#how-it-works">How it works</a>
</li>
<li>
<a href="#caveats">Caveats</a>
</li>
</ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                                    <li data-description="Use the Event Utility to attach simple DOM event handlers.">
                                        <a href="basic-example.html">Simple DOM Events</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Using the synthetic event API to create a DOM event that fires in response to arrow keys being pressed.">
                                        <a href="synth-example.html">Creating an Arrow Event for DOM Subscription</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Supporting cross-device swipe gestures, using the event-move gesture events">
                                        <a href="swipe-example.html">Supporting A Swipe Left Gesture</a>
                                    </li>
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                        </ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples That Use This Component</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                            
                                
                            
                                
                            
                                
                                    <li data-description="Shows how to extend the base widget class, to create your own Widgets.">
                                        <a href="../widget/widget-extend.html">Extending the Base Widget Class</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Creating an accessible menu button using the Focus Manager Node Plugin, Event&#x27;s delegation support and mouseenter event, along with the Overlay widget and Node&#x27;s support for the WAI-ARIA Roles and States.">
                                        <a href="../node-focusmanager/node-focusmanager-3.html">Accessible Menu Button</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Use IO to request data over HTTP.">
                                        <a href="../io/get.html">HTTP GET to request data</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Example Photo Browser application.">
                                        <a href="../dd/photo-browser.html">Photo Browser</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Portal style example using Drag &amp; Drop Event Bubbling and Animation.">
                                        <a href="../dd/portal-drag.html">Portal Style Example</a>
                                    </li>
                                
                            
                        </ul>
                    </div>
                </div>
            
        </div>
    </div>
</div>

<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>

</body>
</html>
